@{
    ViewData["Title"] = "API 文档 - 同步所有任务状态";
}

<div class="d-flex align-items-center mb-4">
    <h2 class="mb-0">@ViewData["Title"]</h2>
    <span class="badge bg-primary ms-3">v1.0</span>
</div>

<div class="alert alert-info d-flex align-items-center">
    <i class="bi bi-info-circle-fill me-2"></i>
    <div>本文档描述了用于同步所有相关工作任务状态的端点。</div>
</div>

<div class="card mb-4">
    <div class="card-header bg-primary text-white">
        <i class="bi bi-terminal me-2"></i>端点信息
    </div>
    <div class="card-body">
        <div class="table-responsive">
            <table class="table table-bordered table-hover">
                <tbody>
                    <tr>
                        <th class="w-25">HTTP 方法</th>
                        <td><span class="badge bg-info">GET</span></td>
                    </tr>
                    <tr>
                        <th>URL</th>
                        <td><code>/WorkTaskStateInfo/SyncAllStates</code></td>
                    </tr>
                    <tr>
                        <th>描述</th>
                        <td>同步所有非“已处理”状态的工作任务的最新状态。该操作会查询适配器服务以获取最新任务信息，并更新或创建本地任务状态记录。</td>
                    </tr>
                </tbody>
            </table>
        </div>
    </div>
</div>

<div class="card mb-4">
    <div class="card-header bg-primary text-white">
        <i class="bi bi-shield-lock me-2"></i>认证
    </div>
    <div class="card-body">
        <p>此端点通常通过应用程序的现有身份验证和授权机制进行保护（例如，要求用户登录并具有特定角色）。没有特定于此端点的额外认证参数。</p>
    </div>
</div>

<div class="card mb-4">
    <div class="card-header bg-primary text-white">
        <i class="bi bi-input-cursor-text me-2"></i>请求参数
    </div>
    <div class="card-body">
        <p>此 GET 请求不需要任何特定的查询参数或请求体。</p>
    </div>
</div>

<div class="card mb-4">
    <div class="card-header bg-primary text-white">
        <i class="bi bi-code-square me-2"></i>示例请求
    </div>
    <div class="card-body">
        <div class="mb-3">
            <h5 class="mb-2">URL</h5>
            <div class="input-group">
                <span class="input-group-text bg-light">GET</span>
                <input type="text" class="form-control" value="/WorkTaskStateInfo/SyncAllStates" readonly>
            </div>
        </div>
    </div>
</div>

<div class="card mb-4">
    <div class="card-header bg-primary text-white">
        <i class="bi bi-arrow-return-right me-2"></i>响应
    </div>
    <div class="card-body">
        <div class="mb-4">
            <h5 class="mb-3">
                成功响应
            </h5>
            <p>成功执行后，端点将用户重定向到 <code>WorkTaskStateInfo/Index</code> 视图。</p>
            <p>同时，会在 <code>TempData["SuccessMessage"]</code> 中设置一条成功消息，例如：</p>
            <pre><code class="language-text">成功同步 N 条任务状态。更新 X 条，新增 Y 条。</code></pre>
        </div>

        <div>
            <h5 class="mb-3">
                错误响应
            </h5>
            <p>如果同步过程中发生错误，端点仍会将用户重定向到 <code>WorkTaskStateInfo/Index</code> 视图。</p>
            <p>同时，会在 <code>TempData["ErrorMessage"]</code> 中设置一条错误消息，例如：</p>
            <pre><code class="language-text">同步状态时出错: [具体的错误信息]</code></pre>
        </div>
    </div>
</div>

<div class="card mb-4">
    <div class="card-header bg-primary text-white">
        <i class="bi bi-gear me-2"></i>工作原理
    </div>
    <div class="card-body">
        <p>此端点执行以下操作来同步任务状态：</p>
        <ol>
            <li>从数据库中检索所有当前状态不是“已处理” (<code>Entities.WorkTaskStatus.Processed</code>) 的 <code>WorkTaskStateInfo</code> 记录。</li>
            <li>将这些记录按其关联的实体全名 (<code>EntityFullName</code>) 进行分组。</li>
            <li>对于每个实体分组：
                <ul>
                    <li>获取该分组下所有不重复的实体键值 (<code>EntityKeyValue</code>) 列表。</li>
                    <li>如果实体键值列表为空，则跳过此分组的处理。</li>
                    <li>构造一个 <code>GetAllProcessingWorkTasksByEntityTypeInputDto</code> 对象，其中包含当前分组的 <code>EntityFullName</code> 和收集到的 <code>EntityKeyValues</code> 列表。</li>
                    <li>调用 <code>IWorkTaskAdapterService.GetAllProcessingWorkTasksByEntityTypeAsync(inputDto)</code> 方法。此方法是关键的集成点，它负责与外部系统（例如，另一个微服务或第三方任务管理平台）进行通信，以获取指定实体类型和相应键值列表的最新工作任务详细信息 (<code>WorkTaskDto</code>)。该适配器服务封装了与外部数据源交互的逻辑，确保本系统能够获取到最新的任务状态和名称等信息。</li>
                </ul>
            </li>
            <li>遍历从适配器服务 (<code>GetAllProcessingWorkTasksByEntityTypeAsync</code>) 返回的每个任务数据传输对象 (<code>WorkTaskDto</code>)：
                <ul>
                    <li>根据 <code>taskDto</code> 中的 <code>EntityFullName</code> 和 <code>EntityKeyValue</code>，在本地数据库中查找已存在的 <code>WorkTaskStateInfo</code> 记录。</li>
                    <li>如果找到了匹配的本地记录 (<code>existingState</code>)：
                        <ul>
                            <li>比较 <code>existingState</code> 的当前 <code>WorkTaskStatus</code> (转换为 <code>Entities.WorkTaskStatus</code> 枚举) 与 <code>taskDto.workTaskStatus</code>，以及 <code>existingState.ProcessName</code> 与 <code>taskDto.Name</code>。</li>
                            <li>如果状态或名称任一发生变化，则更新 <code>existingState</code> 的 <code>WorkTaskStatus</code>、<code>ProcessName</code> 和 <code>UpdatedTime</code>。同时，增加已更新记录的计数器 (<code>updatedCount</code>)。</li>
                        </ul>
                    </li>
                    <li>如果没有找到匹配的本地记录：
                        <ul>
                            <li>创建一个新的 <code>WorkTaskStateInfo</code> 实体。</li>
                            <li>使用 <code>taskDto</code> 中的信息填充新实体的属性，包括 <code>EntityFullName</code>, <code>EntityKeyValue</code>, <code>WorkTaskStatus</code> (从 <code>taskDto.workTaskStatus</code> 转换), <code>ProcessName</code> (来自 <code>taskDto.Name</code>), <code>UpdatedTime</code> (当前时间), <code>CreatedTime</code> (当前时间), 以及 <code>CreatedUserId</code> (当前用户)。</li>
                            <li>将新创建的实体添加到数据库上下文中，并增加已创建记录的计数器 (<code>createdCount</code>)。</li>
                        </ul>
                    </li>
                </ul>
            </li>
            <li>检查是否有任何记录被更新 (<code>updatedCount > 0</code>) 或创建 (<code>createdCount > 0</code>)。</li>
            <li>如果发生了更新或创建操作，则调用 <code>_context.SaveChangesAsync()</code> 将所有更改持久化到数据库，并设置包含更新和创建数量的成功消息到 <code>TempData["SuccessMessage"]</code>。</li>
            <li>如果没有记录被更新或创建，则设置一条提示信息到 <code>TempData["InfoMessage"]</code>。</li>
            <li>无论同步操作的结果如何（成功、无变化或发生异常），最终都会将用户重定向到 <code>WorkTaskStateInfo/Index</code> 视图。</li>
        </ol>
        <div class="alert alert-warning mt-3">
            <i class="bi bi-exclamation-triangle-fill me-2"></i>
            <strong>注意：</strong> 此过程高度依赖于 <code>IWorkTaskAdapterService</code> 及其 <code>GetAllProcessingWorkTasksByEntityTypeAsync</code> 方法的正确实现和其所对接的外部接口/服务的可用性。如果外部服务不可用或返回不正确的数据，可能会影响同步结果的准确性。
        </div>
    </div>
</div>

<div class="card mb-4">
    <div class="card-header bg-primary text-white">
        <i class="bi bi-lightbulb me-2"></i>使用场景
    </div>
    <div class="card-body">
        <ul>
            <li><strong>定期状态同步：</strong> 可以配置为定期作业，以确保本地任务状态与外部系统保持一致。</li>
            <li><strong>手动触发同步：</strong> 管理员可以在需要时手动触发此操作，例如在系统维护或数据校准后。</li>
            <li><strong>问题排查：</strong> 当怀疑本地任务状态与实际状态不符时，可用于强制刷新。</li>
        </ul>
    </div>
</div>

@section Scripts {
    <script>
        // No specific scripts needed for this documentation page as it's informational.
        // If there were interactive elements like API simulation, scripts would go here.
    </script>
}
